Description

Build the issue #3 behavioral harness before the hook and runner rewrite so later Pushgate changes can be exercised against disposable Git repositories instead of manual pushes.

Closes #3.

Type of change

• fix: - Bug fix (patch version bump)
• feat: - New feature (minor version bump)
• feat!: / fix!: - Breaking change (major version bump)
• docs: - Documentation only (no version bump)
• chore: - Maintenance or config (no version bump)
• refactor: - Code restructure, no behaviour change (no version bump)

Changes made

• Add the issue M0: Build hook and runner test harness #3 plan plus a reusable TypeScript hook harness that seeds temporary Git repos, isolates HOME and PATH, stubs deterministic tools and Claude, records stub artifacts, and supports a real bare-remote push smoke path.
• Add behavioral coverage for passing, warning, blocking, missing-tool, missing-provider, provider-failure, filename-with-spaces, ignored-path, deleted-file, and git push --no-verify paths on the current hook surface.
• Extend local and Linux CI verification with shared shell syntax and ShellCheck scripts, and update contributor and PR guidance to use those commands.
• Fix legacy ignore_paths list parsing to use portable awk whitespace classes and keep the ShellCheck directive attached to the case command it governs.
• Document the harness and config loader/type contracts with TSDoc so the runner-facing helpers and normalized v2 config boundary are easier to extend.

Testing

• pnpm test
• pnpm build
• pnpm run check:shell
• pnpm run lint:shell
• Verified locally on macOS with disposable Git repositories and stubbed tool/provider commands
• Verified on Linux outside GitHub Actions

Checklist

• Commit messages follow Conventional Commits
• No eval, heredoc variable expansion, or unquoted variable interpolation added to shell scripts
• File lists remain passed as arrays instead of interpolated strings
• VERSION, CHANGELOG.md, .release-please-manifest.json, and release-please-config.json were not manually edited
• Template table changes are not applicable
• Installer template-name changes are not applicable

Screenshots / output

The new harness asserts behavior through exit codes, focused terminal markers, and stub artifacts rather than snapshotting full terminal output.